Description

Previously, errors were thrown as plain strings or unstructured exceptions, making it impossible for users to programmatically handle different error types. This PR introduces type-safe, structured error handling across the entire codebase.

Changes

1. Codegen Approach

• Added single source of truth for error codes in scripts/errors.config.ts
• Generates matching C++ (ErrorCodes.h) and TypeScript (ErrorCodes.ts) enums
• Preserves JSDoc comments from config to generated files
• Run yarn codegen:errors to regenerate after modifying error definitions

2. Error Structure

All errors now follow a consistent format: {code: number, message: string}

C++ side:

• Throw RnExecutorchError(ErrorCode, "message") instead of std::runtime_error
• Use RnExecutorchInternalError::ErrorName for internal errors
• ExecuTorch runtime errors are passed directly via the variant
• Updated all model files: BaseModel.cpp, LLM.cpp, Detector.cpp, Recognizer.cpp, VerticalOCR.cpp, etc.

TypeScript side:

• Throw ExecutorchError(ETErrorCode.ErrorName, "message") instead of plain Error
• Use parseUnknownError(err) in catch blocks to convert unknown errors
• Updated all modules, controllers, and hooks

3. Error Code Ranges

Currently that's used pretty frivolously and this needs to be fixed.

4. Key Quirk: Different Enums for C++ vs TypeScript

• C++ enum (RnExecutorchInternalError): Only includes internal errors, excludes ExecuTorch runtime errors
• TypeScript enum (ETErrorCode): Includes all errors (internal + ExecuTorch mapped)
• Reason: C++ handles ExecuTorch runtime errors via ErrorVariant = std::variant<RnExecutorchInternalError, executorch::runtime::Error>

5. Documentation

Added error handling documentation at docs/docs/03-typescript-api/04-error-handling.md:

• Overview with example code
• Complete reference of all error codes organized by category
• "When It Occurs" and "How to Handle" guidance for each error
• Best practices for retry logic, input validation, and state management

Important: From Now On

When throwing errors from the native side, always use RnExecutorchError with appropriate error codes from RnExecutorchInternalError enum. This ensures errors are properly serialized across the JSI boundary and can be handled by users.

Introduces a breaking change?

• Yes
• No

Type of change

• Bug fix (change which fixes an issue)
• New feature (change which adds functionality)
• Documentation update (improves or adds clarity to existing documentation)
• Other (chores, tests, code style improvements etc.)

Tested on

• iOS
• Android

Testing instructions

Screenshots

Related issues

Checklist

• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have updated the documentation accordingly
• My changes generate no new warnings

Additional notes